rustdoc: Add unstable `--merge-doctests=yes/no/auto` flag #149565

jyn514 · 2025-12-02T21:59:41Z

This is useful for changing the default for whether doctests are merged or not. Currently, that default is solely controlled by edition = 2024, which adds a high switching cost to get doctest merging. This flag allows opting in even on earlier editions.

Unlike the edition = 2024 default, --merge-doctests=yes gives a hard error if merging fails instead of falling back to running standalone tests. The user has explicitly said they want merging, so we shouldn't silently do something else.

--merge-doctests=auto is equivalent to the current 2024 edition behavior, but available on earlier editions.

Helps with #141240. @epage said in that issue he would like a per-doctest opt-in, and that seems useful to me in addition to this flag, but I think it's a separate use case from changing the default.

rustbot · 2025-12-02T21:59:47Z

r? @notriddle

rustbot has assigned @notriddle.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

src/librustdoc/doctest.rs

jyn514 · 2025-12-02T22:27:05Z

tests/rustdoc-ui/doctest/force-merge-fail.stderr

+doctest_bundle_2018.rs:$LINE:$COL: error: `unmangled_name` redeclared with a different signature: this signature doesn't match the previous declaration
+error: aborting due to 1 previous error
+error: failed to merge doctests
+   |
+   = note: requested explicitly on the command line with `--merge-doctests=yes`


this error kinda sucks, but this is an unstable feature anyway, and with -C save-temps people will actually be able to inspect the merged code, which should make this easier to debug.

oh, maybe this should recommend -C save-temps as a note?

jyn514 · 2025-12-03T01:37:55Z

hm this broke the reference’s doctest somehow

      failures:
      
      ---- items/constant-items.md - Constant_items (line 71) stdout ----
      Test compiled successfully, but it's marked `compile_fail`.
      ---- items/constant-items.md - Constant_items (line 97) stdout ----
      Test compiled successfully, but it's marked `compile_fail`.
      
      failures:
          items/constant-items.md - Constant_items (line 71)
          items/constant-items.md - Constant_items (line 97)

jyn514 · 2025-12-03T17:38:30Z

i'm completely unable to reproduce this :/ i see ci has this output which i don't see locally:

[2025-12-03T00:03:32Z WARN  mdbook::preprocess::cmd] The command wasn't found, is the "spec" preprocessor installed?
[2025-12-03T00:03:32Z WARN  mdbook::preprocess::cmd] 	Command: cargo run --release --manifest-path mdbook-spec/Cargo.toml

jyn514 · 2025-12-03T17:43:07Z

i ran rustdoc +stage2 --test src/items/constant-items.md manually and it doesn't even show the same line numbers as CI :/ what on earth

rustbot · 2025-12-03T17:46:05Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

epage · 2025-12-03T19:19:14Z

src/librustdoc/doctest/make.rs

+                && !(has_macro_def && everything_else.contains("$crate"));
+            can_merge
+        } else {
+            can_merge_doctests != MergeDoctests::Never


Am I reading this correctly that this overrides standalone_crate?

From the PR description (emphasis mine)

This is useful for changing the default for whether doctests are merged or not.

For me, default implies that this is what we do in the absence of other information. standalone_crate is an obvious one for being respected. compile_fail is another. test_harness I'm unsure about.

Now, for any of the detection based on the code (global allocator, crate attrs, macros, $crate, etc, I see that being part of the autodetection.

In case it is relevant, https://github.com/epage/rust/commits/merged_crate is where I left off on my work on the attribute

excellent catch, omg. fixed this and added a test.

jyn514 · 2025-12-03T20:01:03Z

something really weird is going on with compiletest; locally it applies the normalize-stdout directive, but in CI it ignores it and replaces $DIR. the two don't match, hence the failure, but I don't understand why $DIR would possibly work in CI but not locally.

for now I'm just going to change the normalization to match compiletest's normalization.

jyn514 · 2025-12-03T20:01:56Z

oh, i wonder if this is about absolute vs relative paths :/

jyn514 · 2025-12-03T20:19:50Z

i think the proper fix here is that rustdoc should use to_embeddable_absolute_path when -Z ui-testing is set. but i've already spent a bunch of time on this so i'm just going to open an issue and hopefully someone gets to it later.

This is useful for changing the *default* for whether doctests are merged or not. Currently, that default is solely controlled by `edition = 2024`, which adds a high switching cost to get doctest merging. This flag allows opt-ing in even on earlier additions. Unlike the `edition = 2024` default, `--merge-doctests=yes` gives a hard error if merging fails instead of falling back to running standalone tests. The user has explicitly said they want merging, so we shouldn't silently do something else. `--merge-doctests=auto` is equivalent to the current 2024 edition behavior, but available on earlier editions.

This allows viewing failed merged doctests.

epage · 2025-12-03T22:43:50Z

src/librustdoc/doctest/make.rs

-                && crate_attrs.is_empty()
+            // We try to look at the contents of the test to detect whether it should be merged.
+            // This is not a complete list of possible failures, but it catches many cases.
+            let will_probably_fail = has_global_allocator


Don't know why I'm getting a chuckle at that variable name :)

rustbot assigned notriddle Dec 2, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Dec 2, 2025

This comment was marked as resolved.

Sign in to view

This comment has been minimized.

Sign in to view

jyn514 changed the title ~~rustdoc: Add unstable --merge-doctests=yes/no flag~~ rustdoc: Add unstable --merge-doctests=yes/no/auto flag Dec 2, 2025

jyn514 force-pushed the force-doctest-merge branch 2 times, most recently from dde2ec7 to 0ff6d88 Compare December 2, 2025 22:23

jyn514 commented Dec 2, 2025

View reviewed changes

src/librustdoc/doctest.rs Show resolved Hide resolved

jyn514 commented Dec 2, 2025

View reviewed changes

This comment has been minimized.

Sign in to view

rustbot added the A-run-make Area: port run-make Makefiles to rmake.rs label Dec 2, 2025

This comment has been minimized.

Sign in to view

jyn514 force-pushed the force-doctest-merge branch from b1e2ca9 to e2aa3fc Compare December 3, 2025 17:46

epage reviewed Dec 3, 2025

View reviewed changes

This comment has been minimized.

Sign in to view

jyn514 mentioned this pull request Dec 3, 2025

rustdoc doctest UI suite shouldn't need to manually normalize $DIR #149616

Open

jyn514 added 2 commits December 3, 2025 15:48

Support -C save-temps in rustdoc

3aa4ece

This allows viewing failed merged doctests.

jyn514 mentioned this pull request Dec 3, 2025

Allow running x test reference locally #149617

Closed

jyn514 force-pushed the force-doctest-merge branch from 4a30a64 to 646667a Compare December 3, 2025 22:41

--merge-doctests is a default, not an override

415953a

jyn514 force-pushed the force-doctest-merge branch from 646667a to 415953a Compare December 3, 2025 22:43

epage reviewed Dec 3, 2025

View reviewed changes

rustdoc: Add unstable --merge-doctests=yes/no/auto flag #149565

Are you sure you want to change the base?

rustdoc: Add unstable --merge-doctests=yes/no/auto flag #149565

Conversation

jyn514 commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Dec 2, 2025

Uh oh!

This comment was marked as resolved.

This comment has been minimized.

Uh oh!

jyn514 Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

jyn514 commented Dec 3, 2025

Uh oh!

jyn514 commented Dec 3, 2025

Uh oh!

jyn514 commented Dec 3, 2025

Uh oh!

rustbot commented Dec 3, 2025

Uh oh!

epage Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

epage Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

jyn514 Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

jyn514 commented Dec 3, 2025

Uh oh!

jyn514 commented Dec 3, 2025

Uh oh!

jyn514 commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

epage Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

rustdoc: Add unstable `--merge-doctests=yes/no/auto` flag #149565

rustdoc: Add unstable `--merge-doctests=yes/no/auto` flag #149565

jyn514 commented Dec 2, 2025 •

edited

Loading

jyn514 commented Dec 3, 2025 •

edited

Loading